========================================================================
    JoyPad Mach3 PlugIn version 0.5 beta by Joakim Hjort, 2009
========================================================================

Disclaimer:
-----------
Use this plugin AT YOUR OWN RISK!
This software is provided "as is", without any warranty of any type or
nature - any use is completely at your own risk.

This software is only tested on Windows XP/SP3 and "Logitech Dual Action"
USB JoyPad. Other versions of Windows and JoyPads may or may not work.

Background (why?):
------------------
As a new Mach3 user with a new hobby desktop mill I wanted an easy way to
control the mill without sitting with the keyboard.
Jogging should be flexible with high and low speeds. Most common functions
should only be one key away.
All this without the use of mouse and preferable while watching the
machine.

I searched the net and found that the cheapest solution would be a new USB
JoyPad prised around 25 euro.
I again searched the web to find a plugin for Mach3 to attach the JoyPad
to the system, but found none (Except the JoyStick plugin at the Mach
support homepage). This JoyStick plugin was limited to two axes and no
button support.

As a software developer I decided to write my own plugin for the JoyPad.
C++ is not my prefered programming language, but this could be fun and
an opportunity to brush up my C++ programming skills. As said so done...

The plugin is written with using Mach3 SDK version 2.6 in native C++,
Visual Studio 2008 and relies on Windows build in support for gamedevices.


What can JoyPad plugin do?
--------------------------
The standard JoyPad has 4 axes, POV (Point Of View) or HAT and 12 buttons.
The last 2 buttons is activated when pressing the small joysticks.

The JoyPad supports all 4 axes which can be mapped to 4 of 6 possible
Mach3 axes. The axes must be calibrated in Windows Control Panel before
using them with the plugin to avoid drift (motor running at zero point).
The signal from axe movement is transformed by a third order function
to give very low velocities near zero and still support fuld velocity
at maximum.
Use the config dialog for JoyPad plugin to configure axes (X, Y, Z, ...).

Enabling "Single axe jogging" will autoselect one axe at a time.
To change axe, just zero the joysticks and use another axe.

Each axe can have a scaling factor for 0 to 100%, limiting the maximum
speed for that axe. Normaly this is used on the Z axe to have more precise
jogging.

POV is on the "Logitech Dual Action" USB JoyPad implemented as 8 distinct
directions and can simulate 8 buttons - this is the way I have implemented
this functionality in JoyPad plugin.

As a safty precaussion the two "trigger" buttons (button 5 and 6) are
assigned to shift between two macros for each button.
A macro for safe actions and a macro for potentionally unsafe actions
(like movement, probing, running g-code etc.). The "unsafe" macro will
only be activated when button 5 or button 6 is pressed at the same time.

For jogging the axes button 5 or button 6 must be pressed and hold down -
this can prevent accidents, if ex. the JoyPad is dropped on the floor...

Assignment of buttons is as follows:

                  When button 5 or 6 is pressed
Button #:    Macro called:   POV #: Direction:  Macro called:
1            M801.m1s        H1     N           M821.m1s
2            M802.m1s        H2     NE          M822.m1s
3            M803.m1s        H3     E           M823.m1s
4            M804.m1s        H4     SE          M824.m1s
7            M807.m1s        H5     S           M825.m1s
8            M808.m1s        H6     SW          M826.m1s
9            M809.m1s        H7     W           M827.m1s
10           M810.m1s        H8     NW          M828.m1s
11           M811.m1s
12           M812.m1s

                  When button 5 or 6 is NOT pressed
Button #:    Macro called:   POV #: Direction:  Macro called:
1            M851.m1s        H1     N           M871.m1s
2            M852.m1s        H2     NE          M872.m1s
3            M853.m1s        H3     E           M873.m1s
4            M854.m1s        H4     SE          M874.m1s
7            M857.m1s        H5     S           M875.m1s
8            M858.m1s        H6     SW          M876.m1s
9            M859.m1s        H7     W           M877.m1s
10           M860.m1s        H8     NW          M878.m1s
11           M861.m1s
12           M862.m1s

If the macro for a button is missing, nothing happens - this way a
button can be disabled.

Just create the macros with the names given in the table and fill them
with the VBScript actions for the bottons.
Press a button on the JoyPad and the corresponding macro will be
executed.
Help writing macros can be found at: http://www.machsupport.com

(Macro names can be changed by editing the profile - not in the plugin
config dialog.)

I have provided some sample macros, se installation.


Installation:
-------------
1) Unpack and copy JoyPad.dll file to Mach3 plugin directory.
2) Start Mach3, navigate to pluigin configuration and configure the plugin.
3) Enable the JoyPad plugin.

4) Copy sample macros to Mach3 macro directory.
   !!! BE CAREFUL - Running unknown macros on live installation with machine
   attached can be dangerous!!! I take no responsibility!!!
   It at your own risk!
   --> Se disclamer <--

   Understand what the macros does before using them!

Enjoy... ;-)


Use and copying:
----------------
You may use and copy the plugin as long this ReadMe.JoyPad.txt file is included
in the distribution and the software remains free of charge.
Please don't remove my name from the distributions - I have put a lot og time and
effort in developing this plugin...

At some time, when the code is stable, I plan to release the source under a open
source license, like GPL or LGPL.


Contact and support:
--------------------
I can be contacted at the Mach3 forum (www.machsupport.com), user area51.
As the software is provided "as is" there is no support, but try searching
the Mach3 forum for support.

If you like the software,  find errors or have suggestions to improvements, I would
like to hear about it.
No garanti that I will implement or correct the code - this is a spare time project.


- Joakim Hjort